//+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
//
//   PACKAGE   : dcf
//   FILE      : SubscriberList.java
//   CLASS     : SubscriberList
//   DATE      : 2006-04-01
//   
//   DESCRIPTION
//   The SubscriberList class represents a collection of subscribers. 
//
//   IMPLEMENTATION NOTES
//   This is pretty much a wrapper for a Java collection that holds Subscriber objects. Since we use it
//   regularly, we use the wrapper for convenience. 
//
//   TODO: Eventually we need to clean up this implementation and make both thread-safe as well provide
//         some guarantees regarding the state of the list in the event of an error. This works for now.
//   
//
//+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
//
//   Copyright (c) 2006 by Hal Smith
//
//   Permission is hereby granted, free of charge, to any person obtaining a copy of this source code 
//   (the "Code")to deal with the Code without restriction, including without limitation the rights to use, copy,
//   modify, merge, publish and distribute the Code, and to permit persons to whom the Code is furnished to do 
//   so, subject to the following conditions:
//
//   The above copyright notice and this permission notice shall be included in all copies or substantial 
//   portions of the Software.
//   
//
//+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
//
//   VERSION HISTORY
//
//
//+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

package dcf;

import java.io.Serializable;
import java.util.Vector;


class SubscriberList implements Serializable {
	
	// The container for the subscribers.
	//
	private Vector<Subscriber> subscriberList;
	
	// Constructor.
	// 
	// This operation initializes the subscriber list. If an error occurs while creating the subscriber list
	// the operation will log the error and throw an InitializationException. No other exceptions are thrown 
	// by this operation.
	//
	public SubscriberList() throws InitializationException {
		
		try {
			
			subscriberList = new Vector<Subscriber>();
		
		} catch (Exception e) {
			
			System.out.println("SubscriberList.SubscriberList(initEndpoint, initServiceName):");
			System.out.println("   Unexpected exception occured while creating the subscriber list: "
					           + e.toString());
			
			throw new InitializationException();

		}
	
	} // constructor

	
	// This operation adds the supplied subscriber to the list. If the addition was successful the operation 
	// returns true, otherwise it logs an error and returns false.
	//
	public boolean add(Subscriber s){
		
		// Result to be returned to the caller. True means the update was successful and false means it 
		// wasn't.
		//
		boolean result = true;
		
		
		// If the supplied subscriber is null, log an error and return false. Otherwise, try to add the 
		// subscriber to the vector and return true to the caller. If any errors occur while trying to perform
		// the add, log the error and return false to the caller.
		//
		if (s== null) {
			
			System.out.println("SubscriberList.add(subscriber)");
			System.out.println("   Supplied subscriber is null. Ignoring request.");
			
			result = false;

		} else {
		
			try {
				
				subscriberList.add(s);
				
				result = true;
	
			} catch (Exception e) {
				
				System.out.println("SubscriberList.add(subscriber)");
				System.out.println("   Unexpected exception: " + e.toString());
				
				result = false;
			
			} // try-catch
	
		} // if (s == null) ...
		
		return result;
	
	} // add()
	
	
	// This operation removes the supplied subscriber. There are no exceptions thrown by this operation.
	//
	public void remove(Subscriber s) {
		
		subscriberList.remove(s);
	
	} // remove()
	
	
	// This operation returns the current number of subscribers in the list. There are no exceptions thrown
	// by this operation.
	//
	public int getSubscriptionCount(){
		
		return subscriberList.size();
	
	} // getSubscriptionCount()
	
	

	// This operation returns the subscriber at the specified position within the list. If there is no
	// entry at the specified position, the value null is returned. There are no exceptions thrown by this 
	// operation.
	//
	public Subscriber getSubscriber(int atPosition){
		
		return subscriberList.elementAt(atPosition);
	
	} // getSubscriber()
	
	
	// This operation adds all subscribers in the provided subscriber list to this subscriber list. If the
	// update is successful, the operation returns true. If the supplied list is null or if any error occurs
	// while performing the update an error is logged and false is returned. There are no exceptions thrown 
	// by this operation.
	//
	// NOTES: 
	// (1) This operation is not atomic. There is no guarantee that when the update completes the list
	//     is the explicit union of the before contents of this list and the contents of the provided list.
	//     Other threads may alter the contents of either list while this update is occuring.
	// 
	// (2) In the event of an error during the update the list will be left in an unknown state. That is, 
	//     it may contain none, some or all of the entries in the provided list. 
	//
	public boolean add(SubscriberList subsList) {
		
		// Result to be returned to the caller. True means the update was successful and false means it 
		// wasn't.
		//
		boolean result = false;
		
		// If the subscription list is null, log an error and return false. Otherwise, update the list and,
		// if successful, return true. If an error occurs updating the list, log an error and return false. 
		try {
		
			if (subsList != null) {
	
				subscriberList.addAll(subsList.subscriberList);
				
				result = true;
				
			} else {
				
				System.out.println("SubscriberList.add(subscriberList):");
				System.out.println("   Provided subscriber list was null. Ignoring the request.");
				
				result = false;
				
			}
		
		} catch (Exception e) {
			
			System.out.println("SubscriberList.add(subscriberList):");
			System.out.println("   Unexpected exception: " + e.toString());
			
			result = false;
		 	
		} // try-catch
		
		return result;
	
	} // add()
	
}